ARIA Tooltips

Expected behaviors

  • Hover tooltips appear when moused over and when the triggering element receives focus, then close when the mouse moves away or when focus moves to a different element.
  • Manual tooltips appear when the triggering element is activated, then close when clicked again or when focus moves to a different element.
  • Responsive tooltips appear when validation criteria are met when typing, and close when focus moves to a different element.
  • Error tooltips appear when focus moves away from a field that fails validation, then close when focus moves back to the triggering element.

The 4X ARIA Tooltip module automatically configures all required ARIA attributes and focus handling, in strict accordance with the ARIA specification.

The following attributes are handled automatically by the Tooltip module:

  • role=tooltip
  • aria-describedby
  • aria-description
  • role=region
  • aria-label

Available attributes for the triggering element:

  • data-tooltip : The resource path and pointer to the ID attribute of the tooltip container element. May consist of a traditional id reference within the same document, or a url+id reference for pulling a tooltip in from an external resource, or the tooltip markup and message that should be displayed visually when triggered.
  • data-error : The resource path and pointer to the ID attribute of the error container element. May consist of a traditional id reference within the same document, or a url+id reference for pulling an error tooltip in from an external resource, or the error tooltip markup and message that should be displayed visually when triggered.

HTML syntax

There are many options for setting the content of a tooltip.

Using embedded markup to create a tooltip


<button data-tooltip='<p>Your email address is required to verify your account, but will not be used for any other purpose.</p>'> Why do we need this? </button>

Using CSS selector to reference a tooltip


<label for="passwordId"> Password: </label>
<input data-tooltip="#passwordTooltipId" id="passwordId" type="password">

<div hidden id="passwordTooltipId">
    <p> Important! </p>
    <ul>
        <li> Must be 8 characters in length.</li>
        <li> Must not contain special characters.</li>
        <li> Must not contain any whitespace characters.</li>
    </ul>
</div>

Using URL+id to reference an external tooltip


<button data-tooltip="url/tooltips.php?type=help#tooltipContainerId"> What is this? </button>

Using standard markup for any focusable element configured with JS setup script


<a class="hasTooltip" href="URL"> ONE </a>

<button class="hasTooltip"> TWO </button>

<input class="hasTooltip" type="text" title="THREE" >

The data-error attribute may be implemented using the same syntax as the data-tooltip attribute, and both data-error and data-tooltip attributes are supported on the same element. However, the data-error attribute is only valid on native input elements.

JavaScript syntax

var myTooltipDC = $A.setTooltip( domNodeOrCSSSelectorForTriggeringElement , {
  // Configure functionality key / value mappings
});
  • Module file: Tooltip.js
  • Has no dependencies.
  • Recommended: Velocity.js, VelocityUI.js.

Parameters

  1. A DOM element or CSS selector to specify the triggering element
  2. A configuration map to customize behaviors and options

Configuration


{

// Unique ID for the tooltip instance
id: "UniqueId",

// Optionally specify the tooltip container element within the same document.
// May be a DOM node or CSS selector.
// Not necessary if data-tooltip or data-error is set on the triggering element.
content: "#tooltipContainerId",

// Optionally specify the tooltip to be rendered when referencing external content.
// Not necessary if data-tooltip or data-error is set on the triggering element.
// If set, the content property will be auto-populated with the returned content.
fetch: {
url: "path/file.htm",
data: {
selector: "#tooltipContainerId"
}
},

// Optionally toggle the hidden attribute instead of inserting the tooltip content when rendered.
    toggleHide: true,

// Preload markup in the background when using the Fetch API to load external content.
preload: true,

// Preload images in the background when using the Fetch API to load external content.
preloadImages: true,

// Optionally specify if the tooltip is an alert message.
// If true, a system alert will be fired when the tooltip is rendered.
// As a general practice, tooltips and errors should never be alerts because this can interfere with speech announcement, so use with caution.
isAlert: false,

// Specify that the tooltip is an inline error message.
isError: false,

// Specify that the tooltip will only open when the triggering element receives focus, and not when moused over.
isFocusOnly: false,

// Specify that the tooltip will only open when the triggering element is clicked, and will close when clicked again.
isManualOpen: false,

// Specify that the tooltip will only close when the mouse leaves the tooltip instead of the triggering element.
// Necessary to pass some WCAG guidelines.
isManualClose: true,

// Specify that the tooltip will be displayed only when specific validation criteria are met when typing.
// Use when customized responses are needed to guide user input.
// Only valid on editable native input elements.
isResponsive: false,

// Set validation criteria to pass or fail as needed.
// Only applicable when isResponsive is set to true.
// Only valid on editable native input elements.
validate: function(DC, target) {
// 'target' is the input element to validate.
var val = target.value.toLowerCase();
// Set the DC.isValid property to track the state of validation.
DC.isValid = val.length > 0;
// Return the string to display as the tooltip if validation passes or failes.
if (DC.isValid) return "You typed something!";
else return "This field desires input.";
},

// Execute a handler every time validate is processed.
// Only applicable when isResponsive is set to true.
// Only valid on editable native input elements.
onValidate: function(DC, target) {
// Do something every time the target is updated.
document.querySelector('input[type="submit"]').disabled = !DC.isValid;
},

// Optionally specify a delay in milliseconds to wait before rendering the tooltip after the triggering element is activated.
delay: 0,

// Optionally specify a timeout length in milliseconds, after which the tooltip will automatically close.
delayTimeout: 0,

// Optionally override the default timeout function that occurs after the delayTimeout length is reached.
timeout: function(dc) {
// Do something...
dc.remove();
},

// Optionally specify a render and remove animation effect for the tooltip.
// Requires the "Animate" module import to function, which is powered by Velocity.js.
// To ignore animation effects, delete the animate object declaration entirely from the setup script.
// View implementations within "Templates/Tooltips" for practical animation usage examples.

style: { display: "none" }, // Set the initial state to hidden in prep for animation.

animate: {

onRender: function(dc, wrapper, next) {

// Specify the render animation effect, including the callback function statement to execute when the animation effect completes.
Velocity(wrapper, "transition.TYPE", {
// Velocity options here, plus the callback declaration after the animation completes.
complete: function() {
next(); // REQUIRED: next() must be executed so control is passed back to 4X for rendering.
}
});

},

onRemove: function(dc, wrapper, next) {

// Specify the removal animation effect, including the callback function statement to execute when the animation effect completes.
Velocity(wrapper, "transition.TYPE", {
// Velocity options here, plus the callback declaration after the animation completes.
complete: function() {
next(); // REQUIRED: next() must be executed so control is passed back to 4X for removal.
}
});

}

},

// Optionally run a script after the tooltip finishes rendering.
afterRender: function(DC) {
// DC.container includes the rendered tooltip content.
},

// Optionally run a script after the tooltip is removed.
afterRemove: function(DC) {
// Do something.
}

// Additional DC API properties and methods can be declared here also to customize functionality and behavior.
// To view available options, reference the help docs located at: "Help/DC API/DC Object Configuration"

}

Programmatic control


// Use the DC object that is returned by the $A.setTooltip() function.

// Open the tooltip manually.
myTooltipDC.render(function() {
// Optionally do something after rendering completes.
});

// Close the tooltip manually.
myTooltipDC.remove(function() {
// Optionally do something after removal completes.
});

// Additional DC API properties and methods can be applied here as well.
// To view available options, reference the help docs located at: "Help/DC API/DC Object Properties and Methods"